package lumis.portal.serviceinterface;

import lumis.portal.*;
import lumis.portal.authentication.SessionConfig;
import lumis.portal.serviceinterfaceinstance.ServiceInterfaceInstanceConfig;
import lumis.portal.stability.StableMinor;
import lumis.util.ITransaction;

import org.w3c.dom.Node;

/**
 * The <CODE>ServiceInterface</CODE> interface is used by the service interface container to
 * invoke the service interfaces. Every service interface has to implement this interface, either by
 * directly implementing it, or by using an existing class implementing the ServiceInterface
 * interface.
 * <P>
 * A service interface is a Java technology-based web component. It is managed by the service
 * interface container and processes requests and generates dynamic content as response.
 * ServiceInterfaces are used by portals as pluggable user interface components.
 * <p>
 * The content generated by a service interface is called a fragment. A fragment is a piece of
 * markup (e.g. HTML, XHTML, WML) adhering to certain rules and can be aggregated with other
 * fragments into a complete document. The content of a service interface is normally aggregated
 * with the content of other service interfaces into the portal page.
 * <P>
 * The service interface container instanciates service interfaces, manages their lifecycle and
 * invoking them to process requests. The lifecycle consists of:
 * <ul>
 * <li>initializing the service interface using using the <code>init</code> method
 * <li>request processsing
 * <li>taking the service interface out of service using the <code>destroy</code> method
 * </ul>
 * <p>
 * Request processing is divided into two types:
 * <ul>
 * <li>action requests handled through the <code>processAction</code> method, to perform actions
 * targeted to the service interface
 * <li>render requests handled through the <code>render</code> method, to perform the render
 * operation
 * </ul>
 * 
 * @version $Revision: 13082 $ $Date: 2011-05-27 16:03:12 -0300 (Fri, 27 May 2011) $
 * @since 4.0.9
 */
@StableMinor(version = "6.0", sinceVersion = "4.0")
public interface IServiceInterface
{
	/**
	 * Called by the service interface manager when a service interface definition is registered.
	 * This method allows the Service Interface implementation to set its default values into the
	 * service interface definition xml.
	 * 
	 * @param sessionConfig
	 *            TODO
	 * @param serviceInterfaceXmlNode
	 * @param transaction
	 *            TODO
	 * 
	 * @throws PortalException
	 */
	public void register(SessionConfig sessionConfig, Node serviceInterfaceXmlNode, ITransaction transaction) throws PortalException;

	/**
	 * Called by the service interface container to indicate to a service interface that the service
	 * interface is being placed into service.
	 * <p>
	 * The service interface container calls the <code>init</code> method exactly once after
	 * instantiating the service interface. The <code>init</code> method must complete
	 * successfully before the service interface can receive any requests.
	 * <p>
	 * The service interface container cannot place the service interface into service if the
	 * <code>init</code> method
	 * <ol>
	 * <li>Throws a <code>ServiceInterfaceException</code>
	 * <li>Does not return within a time period defined by the service interface container.
	 * </ol>
	 * 
	 * @param config
	 *            a <code>ServiceInterfaceConfig</code> object containing the service interface's
	 *            configuration and initialization parameters
	 * @exception ServiceInterfaceException
	 *                if an exception has occurred that interferes with the service interface's
	 *                normal operation.
	 * @exception PortalException
	 *                if the service interface cannot perform the initialization at this time.
	 */

	public void load(ServiceInterfaceConfig config) throws ServiceInterfaceException, PortalException;

	/**
	 * Called by the service interface container to indicate to a service interface that the service
	 * interface is being taken out of service.
	 * <p>
	 * Before the service interface container calls the destroy method, it should allow any threads
	 * that are currently processing requests within the service interface object to complete
	 * execution. To avoid waiting forever, the service interface container can optionally wait for
	 * a predefined time before destroying the service interface object.
	 * <p>
	 * This method enables the service interface to do the following:
	 * <ul>
	 * <li>clean up any resources that it holds (for example, memory, file handles, threads)
	 * <li>make sure that any persistent state is synchronized with the service interface current
	 * state in memory.
	 * </ul>
	 * 
	 * @exception ServiceInterfaceException
	 *                if the service interface has problems fulfilling the request
	 * @exception PortalException
	 *                if the service interface is unavailable to process the action at this time
	 */
	public void unload() throws ServiceInterfaceException, PortalException;

	/**
	 * Called by the service container to indicate that a service interface instance has been
	 * initialized
	 */

	/**
	 * @param config
	 *            a <code>ServiceInterfaceInstanceConfig</code> object containing the service
	 *            interface instance's configuration and initialization parameters
	 * @exception ServiceInterfaceException
	 *                if the service interface has problems fulfilling the request
	 * @exception PortalException
	 *                if the service interface is unavailable to process the action at this time
	 */
	public void instanceLoaded(ServiceInterfaceInstanceConfig config) throws ServiceInterfaceException, PortalException;

	/**
	 * Called by the service container to indicate that a service interface instance is about to be
	 * destroyed
	 * 
	 * @param config
	 *            a <code>ServiceInterfaceInstanceConfig</code> object containing the service
	 *            interface instance's configuration and initialization parameters
	 * @exception ServiceInterfaceException
	 *                if the service interface has problems fulfilling the request
	 * @exception PortalException
	 *                if the service interface is unavailable to process the action at this time
	 */
	public void instanceUnLoaded(ServiceInterfaceInstanceConfig config) throws ServiceInterfaceException, PortalException;

	/**
	 * Called by the service container to indicate that a service interface instance has been added
	 * 
	 * @param config
	 *            a <code>ServiceInterfaceInstanceConfig</code> object containing the service
	 *            interface instance's configuration and initialization parameters
	 * @exception ServiceInterfaceException
	 *                if the service interface has problems fulfilling the request
	 * @exception PortalException
	 *                if the service interface is unavailable to process the action at this time
	 */
	public void instanceAdded(ServiceInterfaceInstanceConfig config, ITransaction transaction) throws ServiceInterfaceException, PortalException;

	/**
	 * Called by the service container to indicate that a service interface instance has been
	 * deleted
	 * 
	 * @param config
	 *            a <code>ServiceInterfaceInstanceConfig</code> object containing the service
	 *            interface instance's configuration and initialization parameters
	 * @exception ServiceInterfaceException
	 *                if the service interface has problems fulfilling the request
	 * @exception PortalException
	 *                if the service interface is unavailable to process the action at this time
	 */
	public void instanceDeleted(ServiceInterfaceInstanceConfig config) throws ServiceInterfaceException, PortalException;

	/**
	 * Called by the service interface container to allow the service interface to process an action
	 * request. This method is called if the client request was originated by a URL created (by the
	 * service interface) with the <code>RenderResponse.createActionURL()</code> method.
	 * <p>
	 * Typically, in response to an action request, a service interface updates state based on the
	 * information sent in the action request parameters. In an action the service interface may:
	 * <ul>
	 * <li>issue a redirect
	 * <li>change its window state
	 * <li>change its service interface mode
	 * <li>modify its persistent state
	 * <li>set render parameters
	 * </ul>
	 * <p>
	 * A client request triggered by an action URL translates into one action request and many
	 * render requests, one per service interface in the portal page. The action processing must be
	 * finished before the render requests can be issued.
	 * 
	 * @param request
	 *            the action request
	 * @param response
	 *            the action response
	 * @exception ServiceInterfaceException
	 *                if the service interface has problems fulfilling the request
	 * @exception PortalException
	 *                if the service interface is unavailable to process the action at this time
	 */
	public void processAction(IServiceInterfaceActionRequest request, IServiceInterfaceActionResponse response) throws ServiceInterfaceException, PortalException;

	/**
	 * Called by the service interface container to allow the service interface to generate the
	 * content of the response based on its current state.
	 * 
	 * @param request
	 *            the render request
	 * @param response
	 *            the render response
	 * @exception ServiceInterfaceException
	 *                if the service interface has problems fulfilling the rendering request
	 * @exception PortalException
	 *                if the service interface is unavailable to perform render at this time
	 */
	public void render(IServiceInterfaceRenderRequest request, IServiceInterfaceRenderResponse response) throws ServiceInterfaceException, PortalException;

	/**
	 * Called by the service interface container before rendering the interface client side. This
	 * method would generally print to the beforeWriter any client side scripts that must be loaded
	 * before rendering the interface.
	 * 
	 * @param request
	 *            the render request
	 * @param response
	 *            the render response
	 * @exception ServiceInterfaceException
	 *                if the service interface has problems fulfilling the rendering request
	 * @exception PortalException
	 *                if the service interface is unavailable to perform render at this time
	 */
	public void renderBefore(IServiceInterfaceRenderRequest request, IServiceInterfaceRenderResponse response) throws ServiceInterfaceException, PortalException;
}
